<!doctype html>


<html>
<head>
  <link rel="shortcut icon" href="static/images/favicon.ico" type="image/x-icon">
  <title>functions.js (Closure Library API Documentation - JavaScript)</title>
  <link rel="stylesheet" href="static/css/base.css">
  <link rel="stylesheet" href="static/css/doc.css">
  <link rel="stylesheet" href="static/css/sidetree.css">
  <link rel="stylesheet" href="static/css/prettify.css">

  <script>
     var _staticFilePath = "static/";
     var _typeTreeName = "goog";
     var _fileTreeName = "Source";
  </script>

  <script src="static/js/doc.js">
  </script>


  <meta charset="utf8">
</head>

<body onload="grokdoc.onLoad();">

<div id="header">
  <div class="g-section g-tpl-50-50 g-split">
    <div class="g-unit g-first">
      <a id="logo" href="index.html">Closure Library API Documentation</a>
    </div>

    <div class="g-unit">
      <div class="g-c">
        <strong>Go to class or file:</strong>
        <input type="text" id="ac">
      </div>
    </div>
  </div>
</div>





<div class="colmask rightmenu">
<div class="colleft">
    <div class="col1">
      <!-- Column 1 start -->

<div id="title">
       <span class="fn">functions.js</span>
</div>

<div class="g-section g-tpl-75-25">
  <div class="g-unit g-first" id="description">
    Utilities for creating functions. Loosely inspired by the
 java classes: <a href="http://go/functions.java">http://go/functions.java</a> and <a href="http://go/predicate.java">http://go/predicate.java</a>.
  </div>
  

        <div class="g-unit" id="useful-links">
          <div class="title">Useful links</div>
          <ol>
            <li><a href="closure_goog_functions_functions.js.source.html"><span class='source-code-link'>Source Code</span></a></li>
            <li><a href="http://code.google.com/p/closure-library/source/browse/closure/goog/functions/functions.js">Git</a></li>
          </ol>
        </div>
</div>

<h2 class="g-first">File Location</h2>
  <div class="g-section g-tpl-20-80">
    <div class="g-unit g-first">
      <div class="g-c-cell code-label">functions/functions.js</div>
    </div>
  </div>
<hr/>


   
<br/>

  <div class="legend">
        <span class="key publickey"></span><span>Public</span>
        <span class="key protectedkey"></span><span>Protected</span>
        <span class="key privatekey"></span><span>Private</span>
  </div>









<div class="section">
  <table class="horiz-rule">


  </table>
</div>




  <h2>Global Functions</h2>





<div class="section">
  <table class="horiz-rule">


     <tr class="even entry public">
       <td class="access"></td>






  <td>
    <a name="goog.functions.FALSE"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.functions.</span><span class="entryName">FALSE<span class="args">()</span>
        </span>
      </div>


     <div class="entryOverview">
       Always returns false.
     </div>

   
  </td>


  <td class="view-code">
     <a href="closure_goog_functions_functions.js.source.html#line43">code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>






  <td>
    <a name="goog.functions.NULL"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.functions.</span><span class="entryName">NULL<span class="args">()</span>
        </span>
      </div>


     <div class="entryOverview">
       Always returns NULL.
     </div>

   
  </td>


  <td class="view-code">
     <a href="closure_goog_functions_functions.js.source.html#line57">code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>






  <td>
    <a name="goog.functions.TRUE"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.functions.</span><span class="entryName">TRUE<span class="args">()</span>
        </span>
      </div>


     <div class="entryOverview">
       Always returns true.
     </div>

   
  </td>


  <td class="view-code">
     <a href="closure_goog_functions_functions.js.source.html#line50">code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>






  <td>
    <a name="goog.functions.and"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.functions.</span><span class="entryName">and<span class="args">(<span class="arg">var_args</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type">function (...[?]): boolean</span></div>
      </div>


     <div class="entryOverview">
       Creates a function that returns true if each of its components evaluates
to true. The components are evaluated in order, and the evaluation will be
short-circuited as soon as a function returns false.
For example, (goog.functions.and(f, g))(x) is equivalent to f(x) &amp;&amp; g(x).
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">var_args</span>
        : <div class="fullType">(<span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></span><span>&nbsp;|&nbsp;</span><span class="type">null</span><span>&nbsp;|&nbsp;</span><span class="type">undefined</span>)</div>
        <div class="entryOverview">A list of functions.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type">function (...[?]): boolean</span></div>&nbsp;
            A function that ANDs its component functions.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_goog_functions_functions.js.source.html#line168">code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>






  <td>
    <a name="goog.functions.compose"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.functions.</span><span class="entryName">compose<span class="args">(<span class="arg">fn</span>,&nbsp;<span class="arg">var_args</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type">function (...[?]): T</span></div>
      </div>


     <div class="entryOverview">
       Creates the composition of the functions passed in.
For example, (goog.functions.compose(f, g))(a) is equivalent to f(g(a)).
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">fn</span>
        : <div class="fullType"><span class="type">function (...[?]): T</span></div>
        <div class="entryOverview">The final function.</div>
     </td>
   </tr>
     
   <tr class="odd">
     <td>
        <span class="entryName">var_args</span>
        : <div class="fullType">(<span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></span><span>&nbsp;|&nbsp;</span><span class="type">null</span><span>&nbsp;|&nbsp;</span><span class="type">undefined</span>)</div>
        <div class="entryOverview">A list of functions.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type">function (...[?]): T</span></div>&nbsp;
            The composition of all inputs.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_goog_functions_functions.js.source.html#line122">code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>






  <td>
    <a name="goog.functions.constant"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.functions.</span><span class="entryName">constant<span class="args">(<span class="arg">retValue</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type">function (): T</span></div>
      </div>


     <div class="entryOverview">
       Creates a function that always returns the same value.
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">retValue</span>
        : <div class="fullType"><span class="type">T</span></div>
        <div class="entryOverview">The value to return.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type">function (): T</span></div>&nbsp;
            The new function.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_goog_functions_functions.js.source.html#line32">code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>






  <td>
    <a name="goog.functions.create"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.functions.</span><span class="entryName">create<span class="args">(<span class="arg">constructor</span>,&nbsp;<span class="arg">var_args</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Object">Object</a></span></div>
      </div>


     <div class="entryOverview">
       Generic factory function to construct an object given the constructor
and the arguments. Intended to be bound to create object factories.

Callers should cast the result to the appropriate type for proper type
checking by the compiler.
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">constructor</span>
        : <div class="fullType"><span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></span></div>
        <div class="entryOverview">The constructor for the Object.</div>
     </td>
   </tr>
     
   <tr class="odd">
     <td>
        <span class="entryName">var_args</span>
        : <div class="fullType"><span class="type">*</span></div>
        <div class="entryOverview">The arguments to be passed to the constructor.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Object">Object</a></span></div>&nbsp;
            A new instance of the class given in <code>constructor</code>.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_goog_functions_functions.js.source.html#line229">code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>






  <td>
    <a name="goog.functions.error"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.functions.</span><span class="entryName">error<span class="args">(<span class="arg">message</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></span></div>
      </div>


     <div class="entryOverview">
       Creates a function that always throws an error with the given message.
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">message</span>
        : <div class="fullType"><span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String">string</a></span></div>
        <div class="entryOverview">The error message.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></span></div>&nbsp;
            The error-throwing function.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_goog_functions_functions.js.source.html#line78">code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>






  <td>
    <a name="goog.functions.identity"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.functions.</span><span class="entryName">identity<span class="args">(<span class="arg">opt_returnValue</span>,&nbsp;<span class="arg">var_args</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type">T</span></div>
      </div>


     <div class="entryOverview">
       A simple function that returns the first argument of whatever is passed
into it.
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">opt_returnValue</span>
        : <div class="fullType">(<span class="type">T</span><span>&nbsp;|&nbsp;</span><span class="type">undefined</span>)</div>
        <div class="entryOverview">The single value that will be returned.</div>
     </td>
   </tr>
     
   <tr class="odd">
     <td>
        <span class="entryName">var_args</span>
        : <div class="fullType"><span class="type">*</span></div>
        <div class="entryOverview">Optional trailing arguments. These are ignored.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type">T</span></div>&nbsp;
            The first argument passed in, or undefined if nothing was passed.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_goog_functions_functions.js.source.html#line68">code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>






  <td>
    <a name="goog.functions.lock"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.functions.</span><span class="entryName">lock<span class="args">(<span class="arg">f</span>,&nbsp;<span class="arg">opt_numArgs</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></span></div>
      </div>


     <div class="entryOverview">
       Given a function, create a function that keeps opt_numArgs arguments and
silently discards all additional arguments.
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">f</span>
        : <div class="fullType">(<span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></span><span>&nbsp;|&nbsp;</span><span class="type">null</span>)</div>
        <div class="entryOverview">The original function.</div>
     </td>
   </tr>
     
   <tr class="odd">
     <td>
        <span class="entryName">opt_numArgs</span>
        : <div class="fullType">(<span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Number">number</a></span><span>&nbsp;|&nbsp;</span><span class="type">undefined</span>)</div>
        <div class="entryOverview">The number of arguments to keep. Defaults to 0.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></span></div>&nbsp;
            A version of f that only keeps the first opt_numArgs arguments.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_goog_functions_functions.js.source.html#line93">code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>






  <td>
    <a name="goog.functions.not"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.functions.</span><span class="entryName">not<span class="args">(<span class="arg">f</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type">function (...[?]): boolean</span></div>
      </div>


     <div class="entryOverview">
       Creates a function that returns the Boolean opposite of a provided function.
For example, (goog.functions.not(f))(x) is equivalent to !f(x).
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">f</span>
        : <div class="fullType"><span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></span></div>
        <div class="entryOverview">The original function.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type">function (...[?]): boolean</span></div>&nbsp;
            A function that delegates to f and returns opposite.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_goog_functions_functions.js.source.html#line212">code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>






  <td>
    <a name="goog.functions.or"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.functions.</span><span class="entryName">or<span class="args">(<span class="arg">var_args</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type">function (...[?]): boolean</span></div>
      </div>


     <div class="entryOverview">
       Creates a function that returns true if any of its components evaluates
to true. The components are evaluated in order, and the evaluation will be
short-circuited as soon as a function returns true.
For example, (goog.functions.or(f, g))(x) is equivalent to f(x) || g(x).
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">var_args</span>
        : <div class="fullType">(<span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></span><span>&nbsp;|&nbsp;</span><span class="type">null</span><span>&nbsp;|&nbsp;</span><span class="type">undefined</span>)</div>
        <div class="entryOverview">A list of functions.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type">function (...[?]): boolean</span></div>&nbsp;
            A function that ORs its component functions.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_goog_functions_functions.js.source.html#line191">code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>






  <td>
    <a name="goog.functions.sequence"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.functions.</span><span class="entryName">sequence<span class="args">(<span class="arg">var_args</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></span></div>
      </div>


     <div class="entryOverview">
       Creates a function that calls the functions passed in in sequence, and
returns the value of the last function. For example,
(goog.functions.sequence(f, g))(x) is equivalent to f(x),g(x).
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">var_args</span>
        : <div class="fullType">(<span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></span><span>&nbsp;|&nbsp;</span><span class="type">null</span><span>&nbsp;|&nbsp;</span><span class="type">undefined</span>)</div>
        <div class="entryOverview">A list of functions.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></span></div>&nbsp;
            A function that calls all inputs in sequence.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_goog_functions_functions.js.source.html#line146">code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>






  <td>
    <a name="goog.functions.withReturnValue"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.functions.</span><span class="entryName">withReturnValue<span class="args">(<span class="arg">f</span>,&nbsp;<span class="arg">retValue</span>)</span>
        </span>
        &#8658; <div class="fullType"><span class="type">function (...[?]): T</span></div>
      </div>


     <div class="entryOverview">
       Given a function, create a new function that swallows its return value
and replaces it with a new one.
     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">f</span>
        : <div class="fullType">(<span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Function">Function</a></span><span>&nbsp;|&nbsp;</span><span class="type">null</span>)</div>
        <div class="entryOverview">A function.</div>
     </td>
   </tr>
     
   <tr class="odd">
     <td>
        <span class="entryName">retValue</span>
        : <div class="fullType"><span class="type">T</span></div>
        <div class="entryOverview">A new return value.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<div class="fullType"><span class="type">function (...[?]): T</span></div>&nbsp;
            A new function.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="closure_goog_functions_functions.js.source.html#line109">code &raquo;</a>
  </td>
     </tr>


  </table>
</div>






      <!-- Column 1 end -->
    </div>

        <div class="col2">
          <!-- Column 2 start -->
          <div class="col2-c">
            <h2 id="ref-head">Directory functions</h2>
            <div id="localView"></div>
          </div>

          <div class="col2-c">
            <h2 id="ref-head">File Reference</h2>
            <div id="sideFileIndex" rootPath="" current="functions/functions.js"></div>
          </div>
          <!-- Column 2 end -->
        </div>
</div>
</div>

</body>
</html>
